test(cli): assert serve publishes the port it BOUND, not the one it was asked for - #16979

Fixes #15273

What was wrong

The non-zero arm of packages/cli/test/serve-publishes-bound-port.e2e.test.ts asserted expect(ipc).toBe(asked) under the premise "when that port is free". That premise is a race, not a fact: randomPort() bind-probes a port that is free at that instant and then closes the listener, so on a six-shard shared runner another process can take it in the seconds between the probe and the spawned child's listen(). The child then auto-shifts — which is exactly what the sibling arm of the same file tests on purpose — and the assertion measured the runner rather than the CLI.

Recorded blast radius: it dropped PR #15073 out of the merge queue, rebuilt every entry behind it and burned a 24-minute Test Core cycle for the whole batch, on a pull request whose diff was entirely under scripts/.

The test is not skipped, disabled or quarantined. The property it guards is real; the quantity the assertion pointed at was wrong.

The change — shape 2, as the claim declared

The arm now asserts what #13062 actually cares about: the published port is the port this server BOUND. Two legs, both immune to whether the request was honoured.

• Leg 1 — a client reaches the published port while the child is up. The file's existing instrument (a TCP connect, with its positive and negative arms proved in describe('the instrument…')) is what answers.
• Leg 2 — that port stops answering once this child's process group dies, so the listener was this server and not whatever else held the number. This is the leg that catches the defect in the only population where requested and bound can differ: a boot that published the port it ASKED for while binding another leaves the asked-for port still answering after its own teardown, because something else is what holds it. It is also the orphan check the arm already carried, now doing both jobs explicitly.

The requested-versus-bound relation — the "nothing an ordinary boot publishes may move" half — is kept, not dropped. It is read out of the child's own #12543 auto-shift notice (Port N is in use — serving on M instead.), a statement contemporaneous with its own bind, instead of out of this harness's stale free-check. With no notice the child bound what it was asked for, so the published number must still be byte for byte what these channels published before; with a notice, the published number must be the port the child itself said it took.

reserve-then-release is deliberately not used: triage and the card both identify it as the same race relocated.

packages/cli/src/commands/serve.ts is untouched. The invariant is fully expressible test-side, so no production-side change was needed.

Proof against a real race, not a green box

A green run on an idle box is not evidence a race is closed, so the contended case was produced: a one-off proof file held the port for the whole boot (the same thing the shared runner did to #15073 by accident) and evaluated the OLD and the NEW assertion against one boot. Run at 37f3a0ddd0, then deleted; git diff HEAD and git status --porcelain both empty afterwards.

PROOF asked=34335 published=34336
PROOF drift-notice=requested=34335 bound=34336
PROOF after-teardown reachable(published=34336)=false reachable(asked=34335)=true

 FAIL  OLD ASSERTION — expect(ipc).toBe(asked) — MUST FAIL here
 AssertionError: expected 34336 to be 34335 // Object.is equality

 Test Files  1 failed (1)
      Tests  1 failed | 3 passed (4)

The old assertion fails in byte-for-byte the shape the card recorded (expected 40734 to be 40733); the new assertion passes on the same construction. The third line is leg 2 discriminating on real numbers: it reads FALSE for the port the server bound and TRUE for the port it was asked for — so a publisher that echoed the request would have been read as TRUE and gone red.

⚠️ Which test population collects this file — measured, with controls, not read

The card records this file failing inside a merge-queue build (Test Core (1/6), FAIL integration test/serve-publishes-bound-port.e2e.test.ts) on 2026-09-04. That is no longer how it runs. Measured on this branch at 12874c41dd with vitest list --filesOnly, both directions controlled:

⇒ Two readings follow, and both are stated rather than inherited.

1. This PR's own checks do not exercise this change. Under the default tier the file is in neither the unit nor the integration project, so nothing on this pull request or in the merge queue runs it. The evidence for the change is the local nightly-tier runs and the contended proof above, not a green check on this PR.
2. The card's queue-amplification premise no longer holds today. scripts/nightly-tiers.mjs moved the e2e and live filename tiers off the per-PR and merge-queue runs in ci(test): e2e and live filename tiers move to a nightly run on main #16481, which landed 2026-09-07 08:10Z — three days after the 2026-09-04 07:22Z incident the card records. The card's premise was true when it was filed; the amplification path has since been closed structurally. The defect itself was not: the assertion still raced, it would simply have flaked the nightly run on main instead of the queue. That is why this is a fix and not a closure.

Verification

Every command below was run in a dedicated worktree; heavy runs went through scripts/pm/os-verify-lock.sh and the verdict quoted is the wrapper's own VERDICT command-exit line, never a bare shell status.

• Dependency closure — pnpm --workspace-concurrency=2 --filter '@objectstack/cli^...' build → exit 0 (re-run after merging origin/main).
• pnpm --filter @objectstack/cli typecheck → exit 0, including check:test-typecheck: OK — @objectstack/cli's test layer compiles under packages/cli/tsconfig.test.json. Coverage of the edited file proved rather than assumed: tsc -p tsconfig.test.json --listFiles names it (1 hit; 2105 files in the program; a nonexistent-path control returns 0), and it contributes 0 errors.
• The file itself — OS_TEST_TIERS=nightly pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/serve-publishes-bound-port.e2e.test.ts → 6 passed / 6, twice: once at 37f3a0ddd0 and again on the merged tree at 12874c41dd.
• test/vitest-tiers-partition.test.ts → 22 passed / 22. The diff adds and removes no file and changes no tier signal, so the partition is unmoved — measured, not argued.
• Derived gate families — node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 12874c41dd (change set: 1 path) yielded 46 commands. 44 exit 0. Two are NOT MEASURED rather than red, and neither can be moved by a test-only diff: check:dual-build-cjs-loads printed PREREQUISITE NOT MET — this gate reads built output (it needs a whole-repo build; only the CLI closure was built here) and check:type-check-debt was killed by this seat's own 420s wrapper timeout after printing its OK — 76/80 workspace packages type-checked line.
• Repo-wide lint — the exact pnpm lint command plus a JSON formatter (eslint . --no-inline-config -f json) → exit 0 over a population of 6387 files read from eslint's own config, 0 errors and 0 warnings; the edited file is in that population at 0/0. No narrowing was needed, and none was claimed: the config declares in its own words that this repo "never enables type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY file", so no untouched file's verdict could move regardless. Measured at 12874c41dd.
• pnpm check:nul-bytes → exit 0, plus a hand sweep of the edited file for control bytes (grep -naP over the non-tab, non-newline control range): zero hits.

skip-changeset — measured, not reasoned

packages/cli's files[] is ["dist","README.md","CHANGELOG.md"], which is not the evidence — npm packs a bin target regardless of it (#14874). So the tarball was packed and searched, with positive controls:

entries packed: 505 | unpackedSize: 5702720
NEGATIVE (target)  serve-publishes-bound-port      -> 0
NEGATIVE  any test/ path                           -> 0
NEGATIVE  any *.test.* artefact                    -> 0
POSITIVE  dist/ entries                            -> 500
POSITIVE  dist/commands/serve.*                    -> serve.d.ts, serve.d.ts.map, serve.js, serve.js.map
POSITIVE  #14874 bin/ entries                      -> bin/run.js
POSITIVE  README.md                                -> 1

The instrument is live in both directions: dist/ is populated (the package was built first) and bin/run.js is packed despite files[] naming no bin/, which is the #14874 caveat firing as a control. The edited path appears nowhere. packages/cli/tsconfig.build.json is "include": ["src"], so test/ is not in the build program at all and cannot reach dist/ by any route. ⇒ this diff publishes nothing from any released package.

Clause-② — re-derived from the delivered diff

Clause-②: no

Re-derived here rather than copied from the claim comment. The delivered diff is one file, packages/cli/test/serve-publishes-bound-port.e2e.test.ts. It relaxes no accepted set, widens no schema and no published surface, adds no closed-set member, no export and no registry entry, withdraws no capability and migrates no stored data shape. In the ordinary population the new assertion is character-for-character the old one (ipc === asked); what changed is that the premise behind it is now established by the child instead of guessed by the harness.

验收备注

noted, not filed: the drift-notice regex Port (\d+) is in use — serving on (\d+) instead\. is now spelled in five places — test/serve-port-drift-notice.e2e.test.ts (which pins it end to end), three unit files under src/commands/, and this file. test/helpers/serve-process.ts would be its natural home, but that file is outside this card's fence. Successor: the next card that touches test/helpers/serve-process.ts for port work. Style, not a defect — filed nowhere on purpose.

noted, not filed: bootServe() in this file rejects with a bare serve exited before announcing a port when the child loses the far narrower probe-to-listen() race inside the CLI, where the sibling runServe() helper would have called portContentionError() and named it. That window is microseconds against the seconds this change closes, it was not the mechanism the card recorded, and no run of it was observed here — so it is an observation, not a reproducible defect, and it is deliberately not filed and not fixed in this PR.

Generated by Claude Code